﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<title>Entities</title>
<link href="bootstrap.min.css" type="text/css" rel="stylesheet" />
</head>

<body>

<div class="document-contents">

<h3 id="DocIntro">Introduction</h3>
<p>In a web application, exceptions are usually handled in MVC Controller 
actions and Web API Controller actions. When an exception occurs, application 
user somehow informed about the error and optionally reason of the error.</p>
<p>If error occured in a regular HTTP request, an error page is shown. If an error 
occured in an AJAX request, server sends error information to the client and 
then client handles and shows the error to the user.</p>
<p>Handling exceptions in all web request is a tedious and repeating work. 
ASP.NET Boilerplate <strong>automates</strong> this. You almost never need to 
explicitly handle any exception. ASP.NET Boilerplate handles all exceptions, 
logs them and returns appropriate and formatted response to the client. Also, 
handles these response in the client and show error messages to the user.</p>
<h3 id="DocEnableErrorHandling">Enabling error handling</h3>
<p>To enable error handling, <strong>customErrors</strong> mode must be enabled.</p>
<pre>&lt;customErrors mode=&quot;On&quot; /&gt;</pre>
<p>It also can be 'RemoteOnly' if you do not want to handler errors in local 
computer.</p>

<h3 id="DocNonAjax">Non-Ajax requests</h3>
<p>If request is not AJAX, an error page is shown.</p>
<h4 id="DocShowExceptions">Showing exceptions</h4>
<p>Here, there is an MVC controller action which throws an arbitrary exception:</p>
<pre lang="cs">public ActionResult Index()
{
    throw new Exception(&quot;A sample exception message...&quot;);
}</pre>
<p>Surely, this exception could be thrown by another method that is called from 
this action. ASP.NET Boilerplate handles this exception, logs it and shows 
'<strong>Error.cshtml</strong>' view. You can <strong>customize</strong> this view to show the error. An 
<strong>example</strong> 
Error view (default Error view in ASP.NET Boilerplate templates):</p>
<p>
<img alt="Default Error view" height="187" src="/SiteFiles/Content/Documents/Resources/error-page-default.png" width="722" /></p>
<p>ASP.NET Boilerplate hides details of the exception from users and shows a 
standard (and localizable) error message, 
unless you explicitly throw a <strong>UserFriendlyException</strong>.</p>
<h4 id="DocShowUserFriendlyExceptions">UserFriendlyException</h4>
<p>UserFriendlyException is a special type of exception that is directly shown 
to the user. See the sample below:</p>
<pre lang="cs">public ActionResult Index()
{
    throw new UserFriendlyException(&quot;Ooppps! There is a problem!&quot;, &quot;You are trying to see a product that is deleted...&quot;);
}</pre>
<p>ASP.NET Boilerplate logs it but does not hide exception in this time:</p>
<p>
<img alt="User friendly exception" height="188" src="/SiteFiles/Content/Documents/Resources/error-page-user-friendly.png" width="722" /></p>
<p>So, if you want to show a special error message to users, just throw a 
UserFriendlyException (or an exception derived from it).</p>
<h4 id="DocErrorModel">Error model</h4>

<p>ASP.NET Boilerplate passes an <strong>ErrorViewModel</strong> object as 
model to the Error view:</p>
<pre lang="cs">public class ErrorViewModel
{
    public AbpErrorInfo ErrorInfo { get; set; }

    public Exception Exception { get; set; }
}</pre>
<p><strong>ErrorInfo</strong> contains detailed informations about the error that can be shown to the user. <strong>Exception</strong> 
object is the thrown exception. You can check it and show additional 
informations if you want. For example, we can show validation errors if it's an
<strong>AbpValidationException</strong>:</p>
<p>
<img alt="Validation errors" height="257" src="/SiteFiles/Content/Documents/Resources/error-page-validation.png" width="722" /></p>
<h3 id="DocAjax">AJAX requests</h3>
<p>If this request is an AJAX request, ASP.NET Boilerplate returns a JSON object 
to the client. This is true for both of ASP.NET MVC Controllers and ASP.NET Web 
API Controllers. Sample return object for an error:</p>
<pre lang="js">{
  &quot;targetUrl&quot;: null,
  &quot;result&quot;: null,
  &quot;success&quot;: false,
  &quot;error&quot;: {
    &quot;message&quot;: &quot;An internal error occured during your request!&quot;,
    &quot;details&quot;: &quot;...&quot;
  },
  &quot;unAuthorizedRequest&quot;: false
}</pre>
<p><strong>success: false</strong> indicates that there is an error. <strong>
error</strong> object provides error <strong>message</strong> and <strong>
details</strong>.</p>
<p>When you use ASP.NET Boilerplate's infrastructure to make AJAX request in 
client side, it automatically handles this JSON object and shows error message 
to the user using <a href="/Pages/Documents/Javascript-API/Message">message A<span class="text-primary">PI</span></a>. 
See <a href="/Pages/Documents/Javascript-API/AJAX">AJAX API</a> and
<a href="/Pages/Documents/Dynamic-Web-API">dynamic web api layer</a> for more 
information.</p>
<h3 id="DocExceptionEvent">Exception event</h3>
<p>When ASP.NET Boilerplare handle any exception, it triggers <strong>AbpHandledExceptionData</strong> 
event that can be registered to be informed (See
<a href="/Pages/Documents/EventBus-Domain-Events">eventbus documentation</a> for 
more information about Event Bus). Example:</p>
<pre lang="cs">public class MyExceptionHandler : IEventHandler&lt;AbpHandledExceptionData&gt;, ITransientDependency
{
    public void HandleEvent(AbpHandledExceptionData eventData)
    {
        //TODO: Check eventData.Exception!
    }
}</pre>
<p>If you put this example class into your application (generally into your Web 
project), <strong>HandleEvent</strong> method will be called for all exceptions 
handled by ASP.NET Boilerplate. So, you can investigate the Exception object in 
detail.</p>

</div>

</body>

</html>
